<!DOCTYPE html>
<html>

  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>What's new in Thymeleaf 2.0 - Thymeleaf: java XML/XHTML/HTML5 template engine</title>
    <link rel="stylesheet" type="text/css" media="all" href="css/thymeleaf.css" />
    <link rel="shortcut icon" href="http://www.thymeleaf.org/favicon.ico" />
    <script type="text/javascript" src="https://apis.google.com/js/plusone.js">
      {lang:'en', parsetags:'explicit'}
    </script>
    <script type="text/javascript" src="sh/scripts/shCore.js"></script>
    <script type="text/javascript" src="sh/scripts/shBrushXml.js"></script>
    <script type="text/javascript" src="sh/scripts/shBrushJava.js"></script>
    <script type="text/javascript" src="sh/scripts/shBrushPlain.js"></script>
    <link href="sh/styles/shCore.css" rel="stylesheet" type="text/css" />
    <link href="sh/styles/shThemeThymeleaf.css" rel="stylesheet" type="text/css" />
  </head>


  <body lang="en" dir="ltr">

  <div id="page">

  
   <div id="menu">
     <ul>
       <li><a href="index.html" title="Home">Home</a></li>
       <li><a href="download.html" title="Download">Download</a></li>
       <li><a href="documentation.html" title="Documentation">Documentation</a></li>
       <li><a href="ecosystem.html" title="Ecosystem">Ecosystem</a></li>
       <li><a href="http://forum.thymeleaf.org" title="User Forum">User Forum</a></li>
       <li><a href="issuetracking.html" title="Issue Tracking">Issue Tracking</a></li>
     </ul>
   </div>

   <div id="header">
     <a href="index.html" title="Thymeleaf home"><img src="images/thymeleaflogonameverysmall.png" class="logo" alt="Thymeleaf Template Engine"/></a>
   </div>

   <div id="breadcrumb">
      <a href="index.html">thymeleaf</a>
      ::
      <a href="documentation.html">documentation</a> 
      ::
      <span class="current">what's new in thymeleaf 2.0</span>
   </div>


   <div id="content">

    <h1>What's new in Thymeleaf 2.0</h1>

 
	<p>
	  Thymeleaf 2.0 includes a lot of new features, but many of them &mdash;in fact,
	  the most important ones in terms of effort&mdash; will not be directly visible to 
	  those users that did never have the need to create their own dialects for 
	  extending Thymeleaf's capabilities.
	</p>
	<p>
	  That is why the explanations you are about to read are not necessarily ordered
	  by relevance, but rather by whether they affect <i>normal</i> users or not.
	</p>
	<ul>
	  <li>Affect all users:
	    <ul>
		  <li><a href="#perf">Performance</a></li>
		  <li><a href="#swit">New <kbd>th:switch</kbd>/<kbd>th:case</kbd> attributes in the standard dialects</a></li>
		  <li><a href="#allb">Added <kbd>all-but-first</kbd> value to <kbd>th:remove</kbd></a></li>
		  <li><a href="#lnum">Line number information in errors</a></li>
		  <li><a href="#doms">DOM Selectors</a></li>
		  <li><a href="#frag">Enabled processing of fragmentary templates</a></li>
		  <li><a href="#cach">Generalized cache infrastructure</a></li>
		  <li><a href="#dtds">New XHTML DTDs for the standard dialects</a></li>
		</ul>
	  </li>
	  <li>Affect only users creating their own Thymeleaf extensions:
	    <ul>
		  <li><a href="#ndom">Substituted the standard Java DOM API by a tailor-made DOM representation</a></li>
		  <li><a href="#ipro">Refactored processor system: the <kbd>IProcessor</kbd> hierarchy</a></li>
		  <li><a href="#tmod">Generalized Template Modes: new template reading/writing infrastructure</a></li>
		  <li><a href="#mino">Minor API modifications</a></li>
		</ul>
	  </li>
	</ul>


    <h2><a name="perf"></a>Performance</h2>


    <p>
      Thymeleaf 2.0 includes a complete rewrite of its template execution engine and
      a redesign of most of its internal architecture. This means big improvements
      in performance since 1.1.
    </p>
    <p>
      Users do not have to make any changes in their existing templates in order to benefit from
      these improvements, as these are mainly of internal nature. The only performance
	  modification that could directly affect users is that the 
	  <kbd>TemplateEngine.process(...)</kbd> method now allows specifying a <kbd>java.io.Writer</kbd>
      object as a parameter in order to write the processing results as soon as the DOM tree
      is processed, without the need to create a <kbd>String</kbd> object containing the whole
      results in memory (this is especially useful in web scenarios where 
	  <kbd>HttpServletResponse</kbd> objects contain one of such <i>writers</i>, but it will 
	  not affect Spring MVC users, as this optimization is applied
	  automatically in the <kbd>thymeleaf-spring3</kbd> integration package).
    </p>
    <p>
      A Benchmark has been created for measuring these improvements. You can have a look at
      the results <a href="benchmarking20.html">here</a>.
    </p>
    


    <h2><a name="swit"></a>New <kbd>th:switch</kbd>/<kbd>th:case</kbd> attributes in the standard dialects</h2>

    
    <p>
      The new <kbd>th:switch</kbd> attribute works in a very similar way to the <kbd>switch</kbd>
      structure in the Java language. The expression specified as value is evaluated and its result
      is compared with the result of evaluating expressions in inner <kbd>th:case</kbd> attributes.
    </p>
    
    <script type="syntaxhighlighter" class="brush:html"><![CDATA[
        <div th:switch="${user.role}">
            <p th:case="'admin'">User is an administrator</p>
            <p th:case="#{roles.manager}">User is a manager</p>
        </div>
    ]]></script>

    <p>
      Note that as soon as one <kbd>th:case</kbd> attribute is evaluated as <kbd>true</kbd>,
      every other <kbd>th:case</kbd> attribute in the same <i>switch</i> context is evaluated as <kbd>false</kbd>.
    </p>
    <p>
      The <kbd>default</kbd> option is specified as <kbd>th:case="*"</kbd>.
    </p>
    
    <script type="syntaxhighlighter" class="brush:html"><![CDATA[
        <div th:switch="${user.role}">
            <p th:case="'admin'">User is an administrator</p>
            <p th:case="#{roles.manager}">User is a manager</p>
            <p th:case="*">User is some other thing</p>
        </div>
    ]]></script>



    <h2><a name="allb"></a>Added <kbd>all-but-first</kbd> value to <kbd>th:remove</kbd></h2>


    <p>
      Prototyping a table usually means to add several tuples (<kbd>&lt;tr&gt;</kbd>) to it; the first
      of them being the object of iteration (<kbd>th:each</kbd>) and the rest needing to be removed
      when the template is processed (<kbd>th:remove</kbd>):
    </p>

    <script type="syntaxhighlighter" class="brush:html"><![CDATA[
        <table>
            <tr th:each="user : ${users}">
                <td th:text="${user.name}">John Apricot</td>
            </tr>
            <tr th:remove="all">
                <td>Martha Apple</td>
            </tr>
            <tr th:remove="all">
                <td>Frederic Orange</td>
            </tr>
        </table>
    ]]></script>

    <p>
      A new value for <kbd>th:remove</kbd>, called <kbd>all-but-first</kbd>, does
      exactly that and saves some repetitive code:
    </p>
    
    <script type="syntaxhighlighter" class="brush:html"><![CDATA[
        <table th:remove="all-but-first">
            <tr th:each="user : ${users}">
                <td th:text="${user.name}">John Apricot</td>
            </tr>
            <tr>
                <td>Martha Apple</td>
            </tr>
            <tr>
                <td>Frederic Orange</td>
            </tr>
        </table>
    ]]></script>


    <h2><a name="lnum"></a>Line number information in errors</h2>

	<p>
	  The new DOM representation and the generalized template parsing infrastructure (see below)
	  now enable template parsers to add <i>location</i> information to DOM nodes, which
	  in practice brings the opportunity to output the number of the line in the template
	  where a processing error has been found:
	</p>

    <script type="syntaxhighlighter" class="brush:plain;gutter:false"><![CDATA[
        org.thymeleaf.exceptions.TemplateProcessingException:
        Exception evaluating SpringEL expression: "#fields.hasErrors('*')" (seedstartermng:69)
        org.thymeleaf.spring3.expression.SpelExpressionEvaluator.evaluate(SpelExpressionEvaluator.java:108)
        org.thymeleaf.standard.expression.VariableExpression.executeVariable(VariableExpression.java:116)
        org.thymeleaf.standard.expression.SimpleExpression.executeSimple(SimpleExpression.java:392)
        org.thymeleaf.standard.expression.Expression.execute(Expression.java:228)
        ...
    ]]></script>
	
    <p>
	  Simple as it might seem, this was one of the most asked-for enhancements in Thymeleaf,
	  but the old parsing infrastructure just didn't allow it to be implemented... anyway, now the old
	  parsers are gone, so here it is!
	</p>



    <h2><a name="doms"></a>DOM Selectors</h2>


    
    <p>
      Thymeleaf 1.1 allowed the inclusion of fragments from other templates by specifying 
      these fragments with an XPath expression between square brackets (<kbd>[...]</kbd>),
      like:
    </p>
    
    <script type="syntaxhighlighter" class="brush:html"><![CDATA[
        <div th:include="sometemplate :: [//div[@id='menu']]">
        </div>
    ]]></script>

    <p>
      Nevertheless, XPath execution heavily relies on the use of the standard DOM API, which
      Thymeleaf 2.0 replaces by a tailor-made one. Because of this, XPath support has now been 
      replaced by <i>DOM Selector support</i> and expressions between square brackets
      like the one above will now be considered DOM Selector expressions.  
    </p>
    
    <p>
      And what is a DOM Selector? It is an object of class <kbd>org.thymeleaf.dom.DOMSelector</kbd>
      that allows you to use a subset of the XPath syntax in order to select a specific region
      of the original DOM tree. Allowed syntax is as follows:
    </p>

    <ul>
      <li><kbd>/x</kbd> means <i>direct children of the current node with name <kbd>x</kbd></i>.</li>
      <li><kbd>//x</kbd> means <i>children of the current node with name <kbd>x</kbd>, at any depth</i>.</li>
      <li><kbd>x[@z='v']</kbd> means <i>elements with name <kbd>x</kbd> and an attribute called z with
          value "v"</i>.</li>
      <li><kbd>x[@z1='v1' and @z2='v2']</kbd> means <i>elements with name <kbd>x</kbd> and attributes
          <kbd>z1</kbd> and <kbd>z2</kbd> with values "v1" and "v2", respectively</i>.</li>
      <li><kbd>x[i]</kbd> means <i>element with name <kbd>x</kbd> positioned in number <kbd>i</kbd> among
          its siblings</i>.</li>
      <li><kbd>x[@z='v'][i]</kbd> means <i>elements with name <kbd>x</kbd>, attribute <kbd>z</kbd> with
          value "v" and positioned in number <kbd>i</kbd> among its siblings that also match this
          condition</i>.</li>
    </ul>
 
    <p>
      So the following will still be completely valid in 2.0:
    </p>
    
    <script type="syntaxhighlighter" class="brush:html"><![CDATA[
        <div th:include="sometemplate :: [//div[@id='menu']]">
        </div>
    ]]></script>



    <h2><a name="frag"></a>Enabled processing of fragmentary templates</h2>

    <p>
	  Prior to 2.0, Thymeleaf was not adequately designed to process templates that could not be
	  considered <i>complete documents</i> from an XML perspective, which limited its scope
	  of applicability in scenarios where it was needed to process only fragments or components
	  of higher-level user interfaces.
	</p>
	
	<p>
	  The new engine architecture in 2.0 completely removes this restriction so that Thymeleaf
	  can be used to process templates which could be, for example, no longer than a simple
	  &lt;div&gt; block.
	</p>



    <h2><a name="cach"></a>Generalized cache infrastructure</h2>


    <p>
	  Thymeleaf 2.0 completely generalizes the cache infrastructure already present in
	  previous versions. The reason to do this is to give the user complete control over
	  what caches are used or not, and how these should work.
    </p>
	<p>
	  The new <kbd>ICacheManager</kbd> interface defines an extension point that will allow
	  the user to specify his/her own caches (implementations of <kbd>ICache</kbd>) for
	  templates, fragments, externalized messages and expressions.
	</p>
	<p>
	  Also, a standard implementation is included (<kbd>StandardCacheManager</kbd>), providing
	  an easy-to-use API for configuring cache sizes and behaviour without the need of 
	  developing custom implementations of the interface.
	</p>
	
    <script type="syntaxhighlighter" class="brush:java"><![CDATA[
        StandardCacheManager manager = new StandardCacheManager();
        manager.setTemplateCacheMaxSize(5);
        manager.setExpressionCacheUseSoftReferences(false);

        templateEngine.setCacheManager(manager);
    ]]></script>

    

    <h2><a name="dtds"></a>New XHTML DTDs for the standard dialects</h2>


    <p>
      The new <kbd>th:switch</kbd> and <kbd>th:case</kbd> attributes require a change in the existing
      Thymeleaf DTDs (those specified with a <kbd>DOCTYPE SYSTEM</kbd> clause), in order
      to include this new attribute and allow its validation.
    </p>

    <p>
      New versions of the DTDs for the Standard and SpringStandard dialects
      have been created, so that the old <kbd>DOCTYPE</kbd> declarations:
    </p>
    
    <script type="syntaxhighlighter" class="brush:html"><![CDATA[
        <!DOCTYPE html SYSTEM "http://www.thymeleaf.org/dtd/xhtml1-strict-thymeleaf-2.dtd">
        <!DOCTYPE html SYSTEM "http://www.thymeleaf.org/dtd/xhtml1-transitional-thymeleaf-2.dtd">
        <!DOCTYPE html SYSTEM "http://www.thymeleaf.org/dtd/xhtml1-frameset-thymeleaf-2.dtd">

        <!DOCTYPE html SYSTEM "http://www.thymeleaf.org/dtd/xhtml1-strict-thymeleaf-spring3-2.dtd">
        <!DOCTYPE html SYSTEM "http://www.thymeleaf.org/dtd/xhtml1-transitional-thymeleaf-spring3-2.dtd">
        <!DOCTYPE html SYSTEM "http://www.thymeleaf.org/dtd/xhtml1-frameset-thymeleaf-spring3-2.dtd">
    ]]></script>

    <p>
      Can now be substituted by new versions containing the new attribute:
    </p>
    
    <script type="syntaxhighlighter" class="brush:html"><![CDATA[
        <!DOCTYPE html SYSTEM "http://www.thymeleaf.org/dtd/xhtml1-strict-thymeleaf-3.dtd">
        <!DOCTYPE html SYSTEM "http://www.thymeleaf.org/dtd/xhtml1-transitional-thymeleaf-3.dtd">
        <!DOCTYPE html SYSTEM "http://www.thymeleaf.org/dtd/xhtml1-frameset-thymeleaf-3.dtd">

        <!DOCTYPE html SYSTEM "http://www.thymeleaf.org/dtd/xhtml1-strict-thymeleaf-spring3-3.dtd">
        <!DOCTYPE html SYSTEM "http://www.thymeleaf.org/dtd/xhtml1-transitional-thymeleaf-spring3-3.dtd">
        <!DOCTYPE html SYSTEM "http://www.thymeleaf.org/dtd/xhtml1-frameset-thymeleaf-spring3-3.dtd">
    ]]></script>



    <h2><a name="ndom"></a>Substituted the standard Java DOM API by a 
        tailor-made DOM representation</h2>


    <p>
      Before version 2.0, Thymeleaf used the standard Java DOM API from <kbd>org.w3c.dom.*</kbd>
	  for modelling documents in memory, and template documents using this API where directly
	  exposed to the diverse hierarchies of processors in dialects. This had the advantage of allowing
	  users to work with a well-known API when developing their own dialects and processors.
    </p>
	<p>
	  Unfortunately, the standard DOM API is extremely heavy and complex, and although Thymeleaf
	  only needed to use a percent of all its features, template documents required a lot
	  of memory space and where slower to process than they could be. Besides, several 
	  Thymeleaf-specific optimizations existed that could not be applied to DOM processing while using 
	  the standard API, so the engine was being penalized even more...
	</p>
    <p>
      Thymeleaf 2.0 completely removes the standard Java DOM API from its architecture and
	  substitutes it by its own DOM representation (<kbd>org.thymeleaf.dom.*</kbd>). This new
	  DOM representation does not adhere to the DOM standard, although it tries to
	  mirror some parts of its structure and concepts in order to be immediately familiar to users.
    </p>
	<p>
	  The <i>new DOM</i> is tailor-made for Thymeleaf, and not only it is much simpler than the old
	  standard, but it also includes as first-class citizens a bunch of important optimizations
	  that allow Thymeleaf to process templates much faster than before, using less resources.
	</p>
	<p>
	  Some advantages of the new DOM are:
	</p>
	<ul>
	  <li>Simpler API, which leads to simpler processors.</li>
	  <li>Lighter objects, allowing a lower memory usage.</li>
	  <li>Ability to <i>precompute</i> the processors to be applied to nodes, so that the 
	      sequence of operations to be performed at each node during template processing 
		  can be cached along with the DOM tree itself in many scenarios, significantly 
		  reducing processing time.</li>
      <li>Allows the generalization of the template parsing infrastructure, so that Thymeleaf
	      2.0 now uses a SAX parser as default &mdash;instead of the old DOM parser, which can
		  still be used but is not default anymore&mdash;. This new parser is much faster than
		  the old one, which leads to an additional improvement in performance, even when a
		  template cache is not being used.</li>
	  <li>Allows the generalization of the template result <i>writing</i> system (converting
	      DOM trees into the desired output), so that new template formats can be made
		  available. Together with parser generalization, this will effectively allow the
		  generalization of the whole <i>template mode</i> infrastructure, as we will see 
		  below.</li>
	</ul>




    <h2><a name="ipro"></a>Refactored processor system: the <kbd>IProcessor</kbd> hierarchy</h2>


    <p>
      In Thymeleaf 1.1, <i>processors</i> could be classified in two groups:
	  <i>attribute processors</i> and <i>tag processors</i>. The former type were 
	  defined specifically to process DOM elements (<i>tags</i>) based on the 
	  existence of a specific attribute in these elements. The latter type processed
	  DOM elements (<i>tags</i>) just based on their name.
    </p>
	<p>
	  In Thymeleaf 2.0, the new DOM allows a generalization of this schema, so that
	  <i>attribute processors</i> and <i>tag processors</i> (the latter now called
	  <i>element processors</i>) are no longer completely
	  disjoint hierarchies, but instead are children of the new general
	  <kbd>IProcessor</kbd> interface.
	</p>
	<p>
	  And this also means that processors no longer can only apply to DOM elements
	  (<i>tags</i>), but instead can apply to any DOM node of any kind, like
	  Text nodes, comments, etc.
    </p>
    <p>
      <i>Attribute Processors</i> (now extending <kbd>AbstractAttrProcessor</kbd>) and 
	  <i>Element Processors</i> (now extending <kbd>AbstractElementProcessor</kbd>) are still dealt 
	  with in a specific manner at the engine for performance reasons, but they are no longer 
	  the only type of processors. For example, the <i>Text Inliners</i> that were somewhat 
	  hard-coded at the engine in previous versions have now been refactored as 
	  <i>text node processors</i> (extending <kbd>AbstractTextNodeProcessor</kbd>) executing 
	  on Text or CDATA Section nodes, so that their use is consistent with other processors, 
	  and also so that they can be easily extended and included into new dialects created by 
	  developers.
	</p>
	<p>
	  Finally, the <i>processor applicability</i> infrastructure has also been modified in 
	  order to simplify it, resulting in the new <kbd>IProcessorMatcher</kbd> hierarchy 
	  that substitutes the old <kbd>IApplicability</kbd> features. This new API for 
	  specifying when a processor <i>matches</i> (<i>"can be applied to"</i>) a DOM node 
	  is more general &mdash;in order to adapt to the new  <kdb>IProcessor</kbd> 
	  needs&mdash; and also enables a simpler specification of applicability constraints 
	  in processors, resulting in simpler extension code.
	</p>
  


    <h2><a name="tmod"></a>Generalized Template Modes: new template reading/writing infrastructure</h2>

  
    <p>
	  As already mentioned, another consequence of the new DOM implementation is the ability
	  to manage <i>generalized template modes</i>.
	</p>
	<p>
	  What this means is that Thymeleaf no longer can only process templates in one of the
	  six <i>standard template modes</i> (<kbd>XML</kbd>, <kbd>VALIDXML</kbd>,
	  <kbd>XHTML</kbd>, <kbd>VALIDXHTML</kbd>, <kbd>HTML5</kbd> and <kbd>LEGACYHTML5</kbd>),
	  but it now allows developers to create their own template modes and use Thymeleaf to
	  process them, just by specifying a <i>template parser</i> and a <i>template writer</i>
	  for each of them, managed by a structure now known as a <i>Template Mode Handler</i> 
	  (<kbd>ITemplateModeHandler</kbd>).
	</p>
	<p>
	  Given the fact that a <i>template parser</i> (<kbd>ITemplateParser</kbd>) is effectively a
	  means to convert input read by a <i>resource resolver</i> into a DOM tree, and also that
	  a <i>template writer</i> is effectively a means to convert a DOM tree into the required
	  output format (an XML document, an HTML5 web page, etc.) this new <i>Template Mode Handler</i>
	  extension point allows developers to make Thymeleaf process any kind of templates as far
	  as they can be modelled as a DOM tree for processing and then written back to their
	  original format for output.
	</p>
	<p>
	  Out-of-the-box, Thymeleaf 2.0 includes the same standard template modes as before, with
	  the difference that they must now be specified at <i>template resolver</i> configuration
	  as Strings instead of using the now-deprecated <kbd>TemplateMode</kbd> enum:
	</p>

    <script type="syntaxhighlighter" class="brush:java"><![CDATA[
        ServletContextTemplateResolver templateResolver = new ServletContextTemplateResolver();
        // templateResolver.setTemplateMode(TemplateMode.HTML5);   DEPRECATED!!
        templateResolver.setTemplateMode("HTML5");              // OK for 2.0!
    ]]></script>


    <h2><a name="mino"></a>Minor API modifications</h2>

  
    <p>
	  Several other minor modifications have been applied to the diverse engine APIs during
	  the architecture rewrite. Namely:
	</p>
    <ul>
	  <li>Created the <kbd>TemplateProcessingParameters</kbd> class containing all the 
	      info available for the processing of the template before its resolution 
		  and parsing, and modified the <kbd>ITemplateResolver</kbd> and
		  <kbd>IResourceResolver</kbd> interfaces to use this class as a parameter instead
		  of the more complex <kbd>Arguments</kbd> class.</li>
	  <li>Made <kbd>Arguments</kbd> objects include the corresponding 
	      <kbd>TemplateResolution</kbd> object created after resolving and parsing each
		  template.</li>
	</ul>

    

   </div>
   
   
   <div id="footer">
     <div id="googleplus">
       <div id="plusone-div" class="plusone"></div>
       <script type="text/javascript">
           gapi.plusone.render('plusone-div',{"size": "small", "count": "true", "href": "http://www.thymeleaf.org"});
       </script>
     </div>
     <div id="twitter">
       <a href="http://twitter.com/thymeleaf" class="twitter-follow-button" data-show-count="false">Follow @thymeleaf</a>
       <script src="http://platform.twitter.com/widgets.js" type="text/javascript"></script>
     </div>
     <div id="copy">
       Copyright &copy; The <a href="team.html">THYMELEAF Team</a>. See <a href="documentation.html">applicable licenses</a>.
     </div>
   </div>
   
  </div>

  <script type="text/javascript">
      SyntaxHighlighter.all();
  </script>

  </body>
  
</html>
